TclX

NAME

INTRODUCTION

This man page contains the documentation for all of the extensions that are added to Tcl 6.2 by Extended Tcl (TclX 6.2b). These extensions provide extend Tcl's capabilities by adding new commands to it, without changing the syntax of standard Tcl. Extended Tcl is a superset of standard Tcl and is built alongside the standard Tcl sources. Extended Tcl has three basic functional areas: A set of new commands, a Tcl shell (i.e. a Unix shell-style command line and interactive environment), and a user-extensible library of useful Tcl procedures, any of which can be automatically loaded on the first attempt to execute it.

The command descriptions are separated into several sections:

o General Commands

o Unix Access Commands

o File I/O Commands

o File Scanning Commands

o Math Commands

o List Maninipulation Commands

o Keyed Lists

o String and Character Manipulation Commands

o XPG/3 Message Catalog Commands

o Tcl Shell and Development Environment

o Help Facility

o Tcl Shell Initialization Sequence

o Tcl Initialization File

o Tcl Shell Variables

o Tcl Shell Procedures

o Tcl Command Autoloading

o Tcl Package Libraries

o Tcl Package Library Procedures

o Tcl Shell Internal Structure

GENERAL COMMANDS

A set of general, useful Tcl commands, includes a command to begin an interactive session with Tcl, a facility for tracing execution, and a looping command.

commandloop [prompt] [prompt2]

Create an interactive command loop for the current TCL interpreter. This command receives commands from stdin and executes them. It is useful TCL scripts that do not normally converse interactively with a user through a Tcl command interpreter, but which sometimes want to enter this mode.

Prompt is a Tcl command string that is evaluated to determine the text of the prompt string. Prompt2 is a command string that is evaluated to determine the ``downlevel prompt'', which is the prompt which is issued for continuation input. When the command terminates, the variables for the prompt hooks will be set to their old value. If these arguments are not specified, the prompt hooks use their current value. Prompt hooks are TCL code that return as their result the prompt to output. The result of the last command executed in the command string (which may be a return) will be used as the prompt.

cmdtrace level|on [noeval] [notruncate] [flush] [procs] [filehandle]

Print a trace statement for all commands executed at depth of level or below (1 is the top level). If on is specified, all commands at any level are traced. The following options are available:

noeval

Causes arguments to be printed unevaluated. If noeval is specified, the arguments are printed before evaluation. Otherwise, they are printed afterwards.

 If the command line is longer than 60 characters, it is truncated to 60 and a "..." is postpended to indicate that there was more output than was displayed. If an evaluated argument contains a space, the entire argument will be enclosed inside of braces (`{}') to allow the reader to visually separate the arguments from each other.

notruncate

Disables the truncation of commands and evaluated arguments.

flush

Causes the output buffer to be flushed after each line is printed. This is useful when tracing C code that cause an application to abort, making it easy to narrow the problem down to the command that caused the abort.

procs

Enables the tracing of procedure calls only. Commands that aren't procedure calls (i.e. calls to commands that are written in C, C++ or some object-compatible language) are not traced if the procs option is specified. This option is particularly useful for greatly reducing the output of cmdtrace while debugging.

filehandle

If specified, then the trace output will be written to the file rather than stdout.

cmdtrace off

Turn off all tracing.

cmdtrace depth

Returns the current maximum trace level, or zero if trace is disabled.

echo [str1..]

Writes zero or more strings to standard output, followed by a newline.

infox option

Return information about Extended Tcl, or the current application. The following infox command options are available:

version

Return the version number of Extended Tcl. The version number for Extended Tcl is generated by combining the base version of the standard Tcl code with a letter indicating the version of Extended Tcl being used. This is the documentation for version tcl6.2b.

patchlevel

Return the patchlevel for Extended Tcl.

appname

Return the symbolic application name of the current application linked with the Extended Tcl library. The C variable tclAppName must be set by the application to return an application specific value for this variable.

applongname

Return a natural language name for the current application. The C variable tclLongAppName must be set by the application to return an application specific value for this variable.

appversion

Return the version number for the current application. The C variable tclAppVersion must be set by the application to return an application-specific value for this variable.

loop var first limit [increment] body

Loop is a looping command, similar in behavior to the Tcl for statement, except that the loop statement achieves substantially higher performance and is easier to code when the beginning and ending values of a loop are known, and the loop variable is to be incremented by a known, fixed amount every time through the loop.

 The var argument is the name of a Tcl variable that will contain the loop index. The loop index is set to the value specified by first. The Tcl interpreter is invoked upon body zero or more times, where var is incremented by increment every time through the loop, or by one if increment is not specified. Increment can be negative in which case the loop will count downwards.

When var reaches limit, the loop terminates without a subsequent execution of body. For instance, if the original loop parameters would cause loop to terminate, say first was one, limit was zero and increment was not specified or was non-negative, body is not executed at all and loop returns.

If a continue command is invoked within body then any remaining commands in the current execution of body are skipped, as in the for command. If a break command is invoked within body then the loop command will return immediately. Loop returns an empty string.

profile [-commands] on

profile off arrayVar
This command is used to collect a performance profile of a Tcl script. It collects data at the Tcl procedure level. The number of calls to a procedure, and the amount of real and CPU time is collected. Time is also collected for the global context. The procedure data is collected by bucketing it based on the procedure call stack, this allows determination of how much time is spent in a particular procedure in each of it's calling contexts.

The on option enables profile data collection. If the -commands option is specifed, data on all commands within a procedure is collected as well a procedures. Multiple occurrences of a command within a procedure are not distinguished, but this data may still be useful for analysis.

The off option turns off profiling and moves the data collected to the array arrayVar. The array is address by a list containing the procedure call stack. Element zero is the top of the stack, the procedure that the data is for. The data in each entry is a list consisting of the procedure call count and the real time and CPU time in milliseconds spent in the procedure (and all procedures it called). The list is in the form {count real cpu}. A Tcl procedure profrep is supplied for reducing the data and producing a report (see Tcl Package Library Procedures section).

UNIX ACCESS COMMANDS

These commands provide access to many basic Unix facilities, including process handling, date and time processing, signal handling, linking and unlinking files, setting file, process, and user attributes, and the executing commands via the shell.

alarm seconds

Instructs the system to send a SIGALRM signal in the specified number of seconds. This is a floating point number, so fractions of a section may be specified. If seconds is 0.0, any previous alarm request is canceled. Only one alarm at a time may be active; the command returns the number of seconds left in the previous alarm. On systems without the setitimer system call, seconds is rounded up to an even number of seconds.

chgrp group filelist

Set the group id of each file in the list filelist to group, which can be either a group name or a numeric group id.

chmod mode filelist

Set permissions of each of the files in the list filelist to mode, where mode is an absolute numeric mode or symbolic permissions as in the UNIX chmod(1) command. To specify a mode as octal, it should be prefixed with a "0" (e.g. 0622).

chown owner|{owner group} filelist

Set owner of each file in the list filelist to owner, which can be a user name or numeric user id. If the first parameter is a list, then the owner is set to the first element of the list and the group is set to the second element. Group can be a group name or numeric group id. If group is {}, then the file group will be set to the login group of the specified user.

convertclock dateString [GMT|{}] [baseClock]

Convert dateString to an integer clock value (see getclock). This command can parse and convert virtually any standard date and/or time string, which can include standard time zone mnemonics. If only a time is specified, the current date is assumed. If the string does not contain a time zone mnemonic, the local time zone is assumed, unless the GMT argument is specified, in which case the clock value is calculated assuming that the specified time is relative to Greenwich Mean Time. If baseClock is specified, it is taken as the current clock value. This is useful for determining the time on a specific day. Some examples are:

    convertclock "14 Feb 92"
    convertclock "Feb 14, 1992 12:20 PM PST"
    convertclock "12:20 PM, Feb 14, 1992"

execl prog [arglist]

Do an execl, replacing the current program (either Extended Tcl or an application with Extended Tcl embedded into it) with prog and passing the arguments in the list arglist.

fmtclock clockval [format] [GMT|{}]

Converts a Unix integer time value, typically returned by getclock, convertclock, or the atime, mtime, or ctime options of the file command, to human-readable form. The format argument is a string that describes how the date and time are to be formatted. Field descriptors consist of a ``%'' followed by a field descriptor character. All other characters are copied into the result. Valid field descriptors are:

    %% - Insert a %.
    %a - Abbreviated weekday name.
    %A - Full weekday name
    %b - Abbreviated month name.
    %B - Full month name.
    %d - Day of month (01 - 31).
    %D - Date as %m/%d/%y.
    %e - Day of month (1-31), no leading zeros.
    %h - Abbreviated month name.
    %H - Hour (00 - 23).
    %I - Hour (00 - 12).
    %j - Day number of year (001 - 366).
    %m - Month number (01 - 12).
    %M - Minute (00 - 59).
    %n - Insert a new line.
    %p - AM or PM.
    %r - Time as %I:%M:%S %p.
    %R - Time as %H:%M.
    %S - Seconds (00 - 59).
    %t - Insert a tab.
    %T - Time as %H:%M:%S.
    %U - Week number of year (01 - 52), Sunday is the first 
         day of the week.
    %w - Weekday number (Sunday = 0).
    %W - Week number of year (01 - 52), Monday is the first 
         day of the week.
    %x - Local specific date format.
    %X - Local specific time format.
    %y - Year within century (00 - 99).
    %Y - Year as ccyy (e.g. 1990)
    %Z - Time zone name.

If format is not specified, "%a %b %d %H:%M:%S %Z %Y" is used. If GMT is specified, the time will be formated as Greenwich Mean Time. If the argument is not specified or is empty, then the local timezone will be used as defined by the TIMEZONE environment variable.

fork

Fork the current Tcl process. Fork returns zero to the child process and the process number of the child to the parent process. If the fork fails, a Tcl error is generated.

If an execl is not going to be performed before the child process does output, or if a close and dup sequence is going to be performed on stdout or stderr, then a flush should be issued against stdout, stderr and any other open output file before doing the fork. Otherwise characters from the parent process pending in the buffers will be output by both the parent and child processes.

getclock

Return the current date and time as a system-dependent integer value. The unit of the value is seconds, allowing it to be used for relative time calculations.

id options

This command provides a means of getting, setting and converting user, group and process ids. The id command has the following options:

id user [name]

id userid [uid]

Set the real and effective user ID to name or uid, if the name (or uid) is valid and permissions allow it. If the name (or uid) is not specified, the current name (or uid) is returned.

id convert userid uid

id convert user name

Convert a user ID number to a user name, or vice versa.

id group [name]

id groupid [gid]

Set the real and effective group ID to name or gid, if the name (or gid) is valid and permissions allow it. If the group name (or gid) is not specified, the current group name (or gid) is returned.

id convert groupid gid

id convert group name

Convert a group ID number to a group name, or vice versa.

id effective user

id effective userid

Return the effective user name, or effective user ID number, respectively.

id effective group

id effective groupid

Return the effective group name, or effective group ID number, respectively.

id process

Return the process ID of the current process.

id process parent

Return the process ID of the parent of the current process.

id process group

Return the process group ID of the current process.

id process group set

Set the process group ID of the current process to its process ID.

kill [signal] processlist

Send a signal to the each process in the list processlist, if permitted. Signal, if present, is the signal number or the symbolic name of the signal, see the signal system call manual page. The leading ``SIG'' is optional when the signal is specified by its symbolic name. The default for signo is 15, SIGTERM.

link [-sym] srcpath destpath

Create a directory entry, destpath, linking it to the existing file, srcpath. If -sym is specified, a symbolic link, rather than a hard link, is created. (The -sym option is only available on systems that support symbolic links.)

mkdir [-path] dirList

Create each of the directories in the list dirList. The mode on the new directories is 777, modified by the umask. If -path is specified, then any non-existent parent directories in the specified path(s) are also created.

rmdir [-nocomplain] dirList

Remove each of the directories in the list dirList. If -nocomplain is specified, then errors will be ignored.

signal action siglist [command]

Specify the action to take when a Unix signal is received by Extended Tcl, or a program that embeds it. Siglist is a list of either the symbolic or numeric Unix signal (the SIG prefix is optional). Action is one of the following actions to be performed on receipt of the signal.

default - Perform system default action when signal is received (see signal system call documentation).

ignore - Ignore the signal.

error - Generate a catchable Tcl error. It will be as if the command that was running returned an error. The error code will be in the form:

    UNIX SIG signame
For the death of child signal, signame will always be SIGCHLD, rather than SIGCLD, to allow writing portable code.

trap - When the signal occures, execute command and continue execution if an error is not returned by command. If will be executed in the global context and the symbolic signal name (e.g. SIGINT) will be supplied in a global variable signalReceived. If an error is returned, then follow the standard Tcl error mechanism. Often command will just do an exit.

get - Retrieve the current settings of the specified signals. A keyed list will be returned were the keys are one of the specified signals and the values are a list cosisting of the action associated with the signal, a 0 if the signal may be delivered (not block) and a 1 if it is blocked. The actions maybe one of `default',`ignore', `error' or `trap. If the action is trap, the third element is the command associated with the action.

block - Block the specified signals from being received. (Posix systems only).

unblock - Allow the specified signal to be received. Pending signals will not occur. (Posix systems only).

The signal action will remain enabled after the specified signal has occurred. The exception to this is SIGCHLD on systems without Posix signals. For these systems, SIGCHLD is not be automatically reenabled. After a SIGCHLD signal is received, a call to wait must be performed to retrieve the exit status of the child process before issuing another signal SIGCHLD ... command. For code that is to be portable between both types of systems, use this approach.

Signals are not processed until after the completion of the Tcl command that is executing when the signal is received.

sleep seconds

Sleep the Extended Tcl process for seconds seconds.

system command

Executes command via the system(3) call. Differs from exec in that system doesn't return the executed command's standard output as the result string, and system goes through the default shell to provide wildcard expansion, redirection, etc, as is normal from an sh command line. The exit code of the command is returned.

times

Return a list containing the process and child execution times in the form:

    utime stime cutime cstime
Also see the times(2) system call manual page. The values are in milliseconds.

umask [octalmask]

Sets file-creation mode mask to the octal value of octalmask. If octalmask is omitted, the current mask is returned.

unlink [-nocomplain] filelist

Delete (unlink) the files whose names are in the list filelist. If -nocomplain is specified, then errors will be ignored.

wait pid

Waits for the process identified by process id pid to terminate, either due to an untrapped signal or call to exit system call. Wait returns a list containing three elements: The first element is the process id of the process that terminated. If the process exited normally, the second element is `EXIT', and the third contains the numeric exit code. If the process terminated due to a signal, the second element is `SIG', and the third contains the signal name. If the process is currently stopped (on systems that support SIGSTP), the second element is `STOP', followed by the signal name.

FILE I/O COMMANDS

These commands extend the stdio-style file I/O capabilities present in Tcl 6.2 and above. These extensions include searching ASCII-sorted data files, copying files, duplicating file descriptors, control of file access options, retrieving open file status, and creating pipes with the pipe system call. An interface to the select system call is available on Unix systems that support it.

It should be noted that Tcl file I/O is implemented on top of the stdio library. By default, the file is buffered. When communicating to a process through a pipe, a flush command should be issued to force the data out. Alternatively, the fcntl command may be used to set the buffering mode of a file to line-buffered or unbuffered.

bsearch filehandle key [retvar] [compare_proc]

Search an opened file containing lines of text sorted into ascending order for a match. Filehandle is a Tcl filehandle as returned by the open command. Key contains the string to match. If retvar is specified, then the line from the file is returned in retvar, and the command returns 1 if key was found, and 0 if it wasn't. If retvar is not specified or is a null name, then the command returns the line that was found, or an empty string if key wasn't found.

By default, the key is matched against the first white-space separated field in each line. The field is treated as an ASCII string. If compare_proc is specified, then it defines the name of a Tcl procedure to evaluate against each line read from the sorted file during the execution of the bsearch command. Compare_proc takes two arguments, the key and a line extracted from the file. The compare routine should return a number less than zero if the key is less than the line, zero if the key matches the line, or greater than zero if the key is greater than the line. The file must be sorted in ascending order according to the same criteria compare_proc uses to compare the key with the line, or errouenous results will occur.

copyfile handle1 handle2

Copies the rest of the file specified by handle1, starting from its current position, to the file specified by handle2, starting from its current position.

dup filehandle [stdhandle]

Duplicate an open file. A file handle is created that addresses the same file as filehandle.

A special case is allowed for duping files to stdin, stdout or stderr. If stdhandle is specified, then it must contain either stdin, stdout, or stderr. In this form, the file corresponding to stdhandle is closed, and the dup is performed from filehandle with the result going to stdhandle.

The procedure shown below will create a child process and set its standard input and output filehandles to a pair of pipe filehandles we pass as arguments. Finally the program does an execl of a specified command, with the program's stdin and stdout coming from and going to our pair of pipes.

    proc ChildProcess {cmd inPipe outPipe} {
        if {[set childPid [fork]] == 0} {
            close stdin
            dup $inPipe stdin
            close $inPipe

            close stdout
            dup $outPipe stdout
            close $outPipe

            execl $cmd
            # will never make it here...
        }
        return $childPid
    }

fcntl handle attribute [value]

This command either sets or clears a file option or returns its current value. If value are not specified, then the current value of attribute is returned. The following attributes may be specified:

RDONLY - The file is opened for reading only. (Get only)

WRONLY - The file is opened for writing only. (Get only)

RDWR - The file is opened for reading and writing. (Get only)

READ - If the file is readable. (Get only).

WRITE - If the file is writable. (Get only).

APPEND - The file is opened for append-only writes. All writes will be forced to the end of the file.

NONBLOCK - The file is to be accessed with non-blocking I/O. See the read system call for a description of how it affects the behavior of file reads.

CLOEXEC - Close the file on an process exec. If the execl command or some other mechanism causes the process to do an exec, the file will be closed if this option is set.

NOBUF - The file is not buffered. If set, then there no stdio buffering for the file.

LINEBUF - Output the file will be line buffered. The buffer will be flushed when a newline is written, when the buffer is full, or when input is requested.

The APPEND, NONBLOCK, and CLOEXEC attributes may be set or cleared by specifying the attribute name and a value 1 to set the attribute and 0 to clear it.

The NOBUF and LINEBUF attributes may only be set (a value of 1) and only one of the options may be selected. Once set, it may not be changed. These options should be set before any I/O operations have been done on the file or data may be lost.

flock options handle [start] [length] [origin]

This command places a lock on all or part of the file specified by handle. The lock is either advisory or mandatory, depending on the mode bits of the file. The lock is placed beginning at relative byte offset start for length bytes. If start or length is omitted or empty, zero is assumed. If length is zero, then the lock always extents to end of file, even if the file grows. If origin is "start", then the offset is relative to the beginning of the file. If it is "current", it is relative to the current access position in the file. If it is "end", then it is relative to the end-of-file (a negative is before the EOF, positive is after). If origin is omitted, start is assumed.

The following options are recognized:

-read - Place a read lock on the file. Multiple processes may be accessing the file with read-locks.

-write - Place a write lock on the file. Only one process may be accessing a file if there is a write lock.

-nowait - If specified, then the process will not block if the lock can not be obtained. With this option, the command returns 1 if the lock is obtained and 0 if it is not.

See your system's fcntl system call documentation for full details of the behavior of file locking. If locking is being done on ranges of a file, it is best to use unbuffered file access (see the fcntl command).

funlock handle [start] [length] [origin]

Remove a locked from a file that was previously placed with the flock command. The arguments are the same as for the flock command, see that command for more details.

fstat handle [item]|[stat arrayvar]

Obtain status information about an open file.

The following keys are used to identify data items:

o atime - The time of last access.

o ctime - The time of last file status change

o dev - The device containing a directory for the file. This value uniquely identifies the file system that contains the file.

o gid - The group ID of the file's group.

o ino - The inode number. This field uniquely identifies the file in a given file system.

o mode - The mode of the file (see the mknod system call).

o mtime - Time when the data in the file was last modified.

o nlink - The number of links to the file.

o size - The file size in bytes.

o tty - If the file is associated with a terminal, then 1 otherwise 0.

o type - The type of the file in symbolic form, which is one of the following values: file, directory, characterSpecial, blockSpecial, fifo, link, or socket.

o uid - The user ID of the file's owner.

If one of these keys is specified as item, then that data item is returned

If stat arrayvar is specified, then the information is returned in the array arrrayvar. Each of the above keys indexes an element of the array containing the data.

If only handle is specified, the command returns the data as a keyed list.

lgets fileId [varName]

Reads the next Tcl list from the file given by fileId and discards the terminating newline character. This command differs from the gets command, in that it reads Tcl lists rather than lines. If the list contains a newline, then that newline will be returned as part of the result. Only a newline not quoted as part of the list indicates the end of the list. There is no corresponding command for outputing lists, as puts will do this correctly. If varName is specified, then the line is placed in the variable by that name and the return value is a count of the number of characters read (not including the newline). If the end of the file is reached before reading any characters then -1 is returned and varName is set to an empty string. If varName is not specified then the return value will be the line (minus the newline character) or an empty string if the end of the file is reached before reading any characters. An empty string will also be returned if a line contains no characters except the newline, so eof may have to be used to determine what really happened.

pipe [handle_var_r handle_var_w]

Create a pipe. If handle_var_r and handle_var_r are specified, then pipe will set the a variable named handle_var_r to contain the handle of the side of the pipe that was opened for reading, and handle_var_w will contain the handle of the side of the pipe that was opened for writing.

If the handle variables are not specified, then a list containing the read and write handlew is returned as the result of the command.

select readhandles [writehandles] [excepthandles] [timeout]

This command allows an Extended Tcl program to wait on zero or more files being ready for for reading, writing, have an exceptional condition pending, or for a timeout period to expire. readhandles, writehandles, excepthandles are each lists of file handles, as returned from open, to query. An empty list ({}) may be specified if a category is not used.

The files specified by the readhandles list are checked to see if data is available for reading. The writehandles are checked if the specified files are clear for writing. The excepthandles are checked to see if an exceptional condition has occured (typically, an error). The write and exception checking is most useful on devices, however, the read checking is very useful when communicating with multiple processes through pipes. Select considers data pending in the stdio input buffer for read files as being ready for reading, the files do. not have to be unbuffered.

Timeout is a floating point timeout value, in seconds. If an empty list is supplied (or the parameter is omitted), then no timeout is set. If the value is zero, then the select command functions as a poll of the files, returning immediately even if none are ready.

If the timeout period expires with none of the files becomming ready, then the command returns an empty list. Otherwise the command returns a list of three elements, each of those elements is a list of the file handles that are ready in the read, write and exception classes. If none are ready in a class, then that element will be the null list. For example:

        select {file3 file4 file5} {file6 file7} {} 10.5

could return

        {file3 file4} {file6} {}

or perhaps

        file3 {} {}

FILE SCANNING COMMANDS

These commands provide a facility to scan files, matching lines of the file against regular expressions and executing Tcl code on a match. With this facility you can use Tcl to do the sort of file processing that is traditionally done with awk. And since Tcl's approach is more declarative, some of the scripts that can be rather difficult to write in awk are simple to code in Tcl.

File scanning in Tcl centers around the concept of a scan context. A scan context contains one or more match statements, which associate regular expressions to scan for with Tcl code to be executed when the expressions are matched.

scancontext [option]

This command manages file scan contexts. A scan context is a collection of regular expressions and commands to execute when that regular expression matches a line of the file. A context may also have a single default match, to be applied against lines that do not match any of the regular expressions. Multiple scan contexts may be defined and they may be reused on multiple files. A scan context is identified by a context handle. The scancontext command takes the following forms:

scancontext create

Create a new scan context. The scanmatch command is used to define patterns in the context. A contexthandle is returned, which the Tcl programmer uses to refer to the newly created scan context in calls to the Tcl file scanning commands.

scancontext delete contexthandle

Delete the scan context identified by contexthandle, and free all of the match statements and compiled regular expressions associated with the specified context.

scanfile contexthandle filehandle

Scan the file specified by filehandle, starting at the current file position. Check all patterns in the scan context specified by contexthandle against it, executing the match commands corresponding to patterns matched.

scanmatch [-nocase] contexthandle [regexp] commands

Specify Tcl commands, to be evaluated when regexp is matched by a scanfile command. The match is added to the scan context specified by contexthandle. Any number of match statements may be specified for a give context. Regexp is a regular expression (see the regexp command). If -nocase is specified as the first argument, the pattern is matched regardless of alphabetic case.

If regexp is not specified, then a default match is specified for the scan context. The default match will be executed when a line of the file does not match any of the regular expressions in the current scancontext.

The array matchInfo is available to the Tcl code that is executed when an expression matches (or defaults). It contans information about the file being scanned and where within it the expression was matched.

matchInfo is local to the top level of the match command unless declared global at that level by the Tcl global command. If it is to be used as a global, it must be declared global before scanfile is called (since scanfile sets the matchInfo before the match code is executed, a subsequent global will override the local variable). The following array entries are available:

matchInfo(line)

Contains the text of the line of the file that was matched.

matchInfo(offset)

The byte offset into the file of the first character of the line that was matched.

matchInfo(linenum)

The line number of the line that was matched. This is relative to the first line scanned, which is usually, but not necessarily, the first line of the file. The first line is line number one.

matchInfo(handle)

The file handle of the file currently being scanned.

All scanmatch patterns that match a line will be processed in the order in which their specifications were added to the scan context. The remainder of the scanmatch pattern-command pairs may be skipped for a file line if a continue is executed by the Tcl code of a preceding, matched pattern.

If a return is executed in the body of the match command, the scanfile command currently in progress returns, with the value passed to return as its return value.  

MATH COMMANDS

These commands make many additional math functions available in Tcl, including minimum, maximum, trig functions, exponent, logarithm, square root, and more. An integer random number generator is provided as well.

The results of floating point calculations will remain floating point numbers (containing a decimal point) and will be accurate to the precision of a double.

All of these commands (except random), take floating point expressions, thus the command can be used without the expr command. This greatly eases the construction of expressions. For example:

set x [sin {1.0 - [cos 3.4]}]

acos expr

Returns the arccosine of expr. expr is in radians.

asin expr

Returns the arcsin of expr. expr is in radians.

atan expr

Returns the arctangent of expr. expr is in radians.

ceil expr

Returns the smallest integer not less than expr (floating point).

cos expr

Returns the cosine of expr. expr is in radians.

cosh expr

Returns the hyperbolic cosine of expr.

exp expr

Returns e to the power of expr.

fabs expr

Returns the absolute value of expr (floating point).

floor expr

Returns the largest integer not greater than expr (floating point).

fmod num1 num2

Returns num1 modulo num2.

max num1 num2 [..numN]

Returns the argument that has the highest numeric value. The arguments, numN may be any interger or floating point values.

min num1 num2 [..numN]

Returns the argument that has the lowest numeric value. The arguments, numN may be any interger or floating point values.

log expr

Returns the natural logarithm of expr.

log10 expr

Returns the logarithm base 10 of expr.

pow num1 num2

Returns num1 to the power of num2.

random limit | seed [seedval]

Generate a pseudorandom integer number greater than or equal to zero and less than limit. If seed is specified, then the command resets the random number generator to a starting point derived from the seedval. This allows one to reproduce pseudorandom number sequences for testing purposes. If seedval is omitted, then the seed is set to a value based on current system state and the current time, providing a reasonably interesting and ever-changing seed.

sin expr

Returns the sin of expr. expr is in radians.

tan expr

Returns the tangent of expr. expr is in radians.

sinh expr

Returns the hyperbolic sin of expr.

sqrt expr

Returns the square root of expr.

tanh expr

Returns the hyperbolic tangent of expr.

LIST MANINIPULATION COMMANDS

Extended Tcl provides two additional list manipulation commands.

lempty list

Determine if the specified list is empty. If empty, 1 is returned, otherwise, 0 is returned. This command is an alternative to comparing a list to an empty string.

lvarcat var string [string...]

This command treats each string argument as a list and concatenates them to the end of the contents of var, forming a a single list. The list is stored back into var and also returned as the result. if var does not exist, it is created.

lvarpop var [index [string]]

The lvarpop command pops (deletes) the element indexed by index from the list contained in the variable var. If index is omitted, then 0 is assumed. If string, is specified, then the deleted element is replaced by string. The replaced or deleted element is returned. Thus ``lvarpop argv 0'' returns the first element of argv, setting argv to contain the remainder of the string.

lvarpush var string [index]

The lvarpush command pushes (inserts) string as an element in the list contained in the variable var. The element is inserted before position index in the list. If index is omitted, then 0 is assumed. If var does not exists, it is created.

KEYED LISTS

Extended Tcl defines a special type of list referred to as keyed lists. These lists provided a structured data type built upon standard Tcl lists. This provides a functionality similar to structs in the C programming language.

A keyed list is a list in which each element contains a key and value pair. These element pairs are stored as lists themselves, where the key is the first element of the list, and the value is the second. The key-value pairs are refered to as fields. This is an example of a keyed list:

    {{NAME {Frank Zappa}} {JOB {musician and composer}}}

If the variable person contained the above list, then keylget person NAME would return {Frank Zappa}. Executing the command:

keylset person ID 106

would make person contain

    {{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}}

Fields may contain subfields; `.' is the seperator character. Subfields are actually fields where the value is another keyed list. Thus the following list has the top level fields ID and NAME, and subfields NAME.FIRST and NAME.LAST:

    {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}

There is no limit to the recursive depth of subfields, allowing one to build complex data structures.

Keyed lists are constructed and accessed via a number of commands. All keyed list management commands take the name of the variable containing the keyed list as an argument (i.e. passed by reference), rather than passing the list directly.

keyldel listvar key

Delete the field specified by key from the keyed list in the variable listvar. This removes both the key and the value from the keyed list.

keylget listvar [key [retvar | {}]]

Return the value associated with key from the keyed list in the variable listvar. If retvar is not specified, then the value will be returned as the result of the command. In this case, if key is not found in the list, an error will result.

If retvar is specified and key is in the list, then the value is returned in the variable retvar and the command returns 1 if the key was present within the list. If key isn't in the list, the command will return 0, and retvar will be left unchanged. If {} is specified for retvar, the value is not returned, allowing the Tcl programmer to determine if a key is present in a keyed list without setting a variable as a side-effect.

If key is omitted, then a list of all the keys in the keyed list is returned.

keylkeys listvar [key]

Return the a list of the keyes in the keyed list in the variable listvar. If keys is specified, then it is the name of a key field who's subfield keys are to be retrieve.

keylset listvar key value [key2 value2 ...]

Set the value associated with key, in the keyed list contained in the variable listvar, to value. If listvar does not exists, it is created. If key is not currently in the list, it will be added. If it already exists, value replaces the existing value. Multiple keywords and values may be specified, if desired.

STRING AND CHARACTER MANIPULATION COMMANDS

The commands provide additional functionality to classify characters, convert characters between character and numeric values, index into a string, determine the length of a string, extract a range of character from a string, replicate a string a number of times, and transliterate a string (similar to the Unix tr program).

cindex string indexExpr

Returns the character indexed by the expression indexExpr (zero based) from string. This command is a shortcut for:

    string index string [expr indexExpr]

clength string

Returns the length of string in characters. This command is a shortcut for:

    string length string

crange string firstExpr lastExpr

Returns a range of characters from string starting at the character indexed by the expression firstExpr (zero-based) until the character indexed by the expression lastExpr. The special keyword end may be specified for last to indicate that the remainder of the string is to be extracted. This command is a shortcut for:

    string range string [expr firstExpr] [expr lastExpr]

csubstr string firstExpr lengthExpr

Returns a range of characters from string starting at the character indexed by the expression firstExpr (zero-based) for lengthExpr characters. The special keyword end may be specified for lengthExpr to indicate that the remainder of the string is to be extracted. This command is a short cut for:

    string range string [expr firstExpr] [expr length-1]

ctype class string

ctype determines whether all characters in string are of the specified class. It returns 1 if they are all of class, and 0 if they are not, or if the string is empty. This command also provides another method (besides format and scan) of converting between an ASCII character and its numeric value. The following ctype commands are available:

ctype alnum string

Tests that all characters are alphabetic or numeric characters as defined by the character set.

ctype alpha string

Tests that all characters are alphabetic characters as defined by the character set.

ctype ascii string

Tests that all characters are an ASCII character (a non-negative number less than 0200).

ctype char number

Converts the numeric value, string, to an ASCII character. Number must be in the range 0 through 255.

ctype cntrl string

Tests that all characters are ``control characters'' as defined by the character set.

ctype digit string

Tests that all characters are valid decimal digits, i.e. 0 through 9.

ctype graph string

Tests that all characters within are any character for which ctype print is true, except for space characters.

ctype lower string

Tests that all characters are lowercase letters as defined by the character set.

ctype ord character

Convert a character into its decimal numeric value. The string must be one character long.

ctype space string

Tests that all characters are either a space, horizontal-tab, carriage return, newline, vertical-tab, or form-feed.

ctype print string

Tests that all characters are a space or any character for which ctype alnum or ctype punct is true or other ``printing character'' as defined by the character set.

ctype punct string

Tests that all characters are made up of any of the characters other than the ones for which alnum, cntrl, or space is true.

ctype upper string

Tests that all characters are uppercase letters as defined by the character set.

ctype xdigit string

Tests that all characters are valid hexadecimal digits, that is 0 through 9, a through f or A through F.

replicate string countExpr

Returns string, replicated the number of times indicated by the expression countExpr.

translit inrange outrange string

Translate characters in string, changing characters occuring in inrange to the corresponding character in outrange. Inrange and outrange may be list of characters or a range in the form `A-M'. For example:

        translit a-z A-Z foobar

XPG/3 MESSAGE CATALOG COMMANDS

These commands provide a Tcl interface to message catalogs that are compliant with the X/Open Portability Guide, Version 3 (XPG/3).

Tcl programmers can use message catalogs to create applications that are language-independent. Through the use of message catalogs, prompts, messages, menus and so forth can exist for any number of languages, and they can altered, and new languages added, without affecting any Tcl or C source code, greatly easing the maintenance difficulties incurred by supporting multiple languages.

A default text message is passed to the command that fetches entries from message catalogs. This allows the Tcl programmer to create message catalogs containing messages in various languages, but still have a set of default messages available regardless of the presence of any message catalogs, and allow the programs to press on without difficulty when no catalogs are present.

Thus, the normal approach to using message catalogs is to ignore errors on catopen, in which case catgets will return the default message that was specified in the call.

The Tcl message catalog commands normally ignore most errors. If it is desirable to detect errors, a special option is provided. This is normally used only during debugging, to insure that message catalogs are being used. If your Unix implementation does not have XPG/3 message catalog support, stubs will be compiled in that will create a version of catgets that always returns the default string. This allows for easy porting of software to environments that don't have support for message catalogs.

Message catalogs are global to the process, an application with multiple Tcl interpreters within the same process may pass and share message catalog handles.

catopen [-fail|-nofail] catname

Open the message catalog catname. This may be a relative path name, in which case the NLSPATH environment variable is searched to find an absolute path to the message catalog. A handle in the form msgcatN is returned. Normally, errors are ignored, and in the case of a failed call to catopen, a handle is returned to an unopened message catalog. (This handle may still be passed to catgets and catclose, causing catgets to simply return the default string, as described above. If the -fail option is specified, an error is returned if the open fails. The option -nofail specifies the default behavior of not returning an error when catopen fails to open a specified message catalog.

catgets catHandle setnum msgnum defaultstr

Retrieve a message form a message catalog. CatHandle should be a Tcl message catalog handle that was returned by catopen. Setnum is the message set number, and msgnum is the message number. If the message catalog was not opened, or the message set or message number cannot be found, then the default string, defaultstr, is returned.

catclose [-fail|-nofail] cathandle

Close the message catalog specified by cathandle. Normally, errors are ignored. If -fail is specified, any errors closing the message catalog file are returned. The option -nofail specifies the default behavior of not returning an error. The use of -fail only makes sense if it was also specified in the call to catopen.

TCL SHELL AND DEVELOPMENT ENVIRONMENT

tcl [-q] [[-f] script]|[-c command] [args]

Tcl starts the interactive Tcl command interpreter. The Tcl shell provides an environment for writing, debugging and executing Tcl scripts. The functionality of the Tcl shell can be easily obtained by any application that includes Tcl.

The tcl command, issued without any arguments, invokes an interactive Tcl shell, allowing the user to interact directly with Tcl, executing any Tcl commands at will and viewing their results.

If script is specified, then the script is executed noninteractively with any additional arguments, args, being supplied in the global Tcl variable `argv'. If command is supplied, then this command (or semicolon-separated series of commands) is executed, with `argv' containing any args.

The Tcl shell is intended as an environment for Tcl program development and execution. While it is not a full-featured interactive shell, it provides a comfortable environment for the interactive development of Tcl code. Note that the package library code described here overrides the unknown command provided as part of the standard Berkeley Tcl library facility, although Tcl source libraries coded to that standard can be loaded and used by Extended Tcl.

The following command line flags are recognized by the Tcl shell command line parser:

-q

Quick initialization flag. If this flag is set the only initialization step performed is to locate the Tcl default file and save its name in the Tcl variable TCLDEFAULT. The file is not evaluated nor is the TclInit.tcl file. This provides for a fast startup, but does not make any of the standard Tcl procedures and facilities available.

-f

Takes the next argument as a script for Tcl to source, rather than entering interactive mode. The -f flag is optional. Normally the first argument that does not start with a `-' is taken as the script to execute unless the `-c' option is specified. Any following arguments are passed to the script via argv, thus any other Tcl shell command-line flags must precede this option.

-c

Take the next argument as a Tcl command to execute. It may contain series of commands to execute, separated by `;'. Any following arguments are passed in argv, thus, as with -f, any other Tcl shell flags must precede this option.

--

Mark the end of the arguments to the Tcl shell. All arguments following this are passed in the Tcl variable argv. This is useful to pass arguments without attempting to execute a Tcl script.

The result string returned by a command executed from the Tcl shell command line is normally echoed back to the user. If an error occurs, then the string result is displayed, along with the error message. The error message will be preceded by the string ``Error:''.

The set command is a special case. If the command is called to set a variable (i.e. with two arguments), then the result will not be echoed. If only one argument, the name of a variable, is supplied to set, then the result will be echoed.

If an unknown Tcl command is entered from the command line, then the Unix command path, specified in the environment variable PATH, will be searched for a command of the same name. If the command is found, it will be executed with any arguments remaining on the Tcl command line being passed as arguments to the command. This feature is provided to enhance the interactive environment for developing Tcl scripts.

Automatic execution of programs in this manner is only supported from the command line, not in script files or in procedures, to reduce confusion and mistakes while programming in Tcl. Scripts should use the Tcl exec or system commands to run Unix commands.  

HELP FACILITY

The help facility allows one to look up help files which where extracted from the standard Tcl manual pages and Tcl scripts during Tcl installation. Help files are structured as a multilevel directory tree of subjects and help files. The following commands and options are provided with the help package:

help

Help, without arguments, lists of all the top-level help subject directories and files.

help subjectdir

Displays all of help files and lower level subject files (if any exist) under the directory subjectdir.

help subjectdir/helpfile

Display the specified help file. The help output is passed through a simple pager if output exceeds 23 lines, pausing waiting for a return to be entered. If any other character is entered, the output is terminated.

helpcd [subjectdir]

Change the current subject directory, which is much like the Unix current directory. If subjectdir is not specified, return to the top-level of the help tree. Help path names may also include ``..'' elements.

helppwd

Displays the current help subject directory.

help help | ?

Displays help on the help facility at any directory level.

apropos pattern

This command locates subjects by searching their one-line descriptions for a pattern. Apropos is useful when you can remember part of the name or description of a command, and want to search through the one-line summaries for matching lines. Full regular expressions may be specified (see the regexp command).

TCL SHELL INITIALIZATION SEQUENCE

The standard Tcl shell initialization consists of the following steps:

Search for a default file. The default file is a Tcl script that is executed to set important Tcl variables that govern startup, such as TCLPATH. The current Extended Tcl version, represented by $ver, is included in the default file name to allow multiple Tcl versions to exists on a system. Note that the Extended Tcl version is the standard Tcl version number with an alphabetic character added to indicated the version of Extended Tcl. (The infox version command will return this version number.)

The Tcl default file is searched for using the following algorithm:

- An environment variable, TCLDEFAULT, is checked for. If present, it is used as the name of the default file.

- A global default file, which is usually either /etc/default/tcl$ver or /usr/local/lib/tcldefault$ver. (Tcl may be compiled to use a different directory if desired).

First, Tcl executes the default file. This file normally sets at least two Tcl variables: TCLPATH, which contains a list of directories that contain tcl source files and libraries, and TCLINIT, the full pathname of the Tcl source file that performs Tcl initialization. Other site-specific variables may also be set in this file.

Next, tcl executes the initialization file specified by the Tcl variable TCLINIT. This is normally the TclInit.Tcl file distributed with Tcl. This file defines the Tcl environment, including standard Extended Tcl procedures and variables.

TCL INITIALIZATION FILE

The Tcl initialization file, normally TclInit.tcl in the main Tcl script directory, initializes the Tcl shell. It defines various Tcl procedures that are required to implement loading of Tcl source from libraries via the package library and autoload facilities.

If the Tcl is invoked interactively, it will source a file named .tclrc in the user's home directory, if it exists. Tcl is viewed primarly as a programming language, not an interactive shell, so the .tclrc is intended for use for loading development utilities, not to support applications, which should not have to rely on the user's environment in such a manner.  

TCL SHELL VARIABLES

The following variables are set and/or used by the Tcl shell.

argv

A list containing the arguments passed in from the command line, excluding arguments used by the Tcl shell. The first element is the first passed argument, not the program name.

interactiveSession

Set to 1 if Tcl shell is invoked interactively, or 0 if the Tcl shell is directly executing a script. Normally checked by scripts so that they can function as a standalone application if specified on the command line, but merely load in and not execute if loaded during an interactive invocation of Tcl.

noAutoExec

If this variable exists and has a value of 1, then the Tcl shell will not attempt to exec an non-existent command as a shell command.

programName

The name that the Tcl shell is executing as. All directory components are removed from the program name.

TCLDEFAULT

Name of the default file that was used to locate all other files used by the Tcl shell.

TCLENV

Array that contains information used internally by various Tcl procedures that are part of the Tcl shell. Entries that you might want to modify are defined here. Don't change any other entries.

TCLENV(topLevelPromptHook)

Contains code to run to generate the prompt used when interactively prompting for commands. The code in this hook will be evaluated and the result will be used for the prompt.

TCLENV(downLevelPromptHook)

Contains code to run to generate the prompt used when interactively prompting for continuation of an incomplete command. The code in this hook will be evaluated and the result will be used for the prompt

TCLINIT

The name of the file that initializes, and does startup processing of, Tcl.

TCLPATH

Path to search to locate Tcl scripts. Used by the load and demand_load commands. The path is a Tcl list (i.e. zero or more space-separated directory names).

TCL SHELL PROCEDURES

The follow additional procedures are defined by the Tcl shell and may be generally useful:

load file Source a file, as with the source command, except search TCLPATH for the file.

searchpath path file Search all directories in the specified path, which is a Tcl list, for the specified file. Returns the full path name of the file, or an empty string if the requested file could not be found.

TCL COMMAND AUTOLOADING

autoload file proc1 [..procN]

The autoload procedure, defined in TclInit.tcl, allows the Tcl programmer to name one or more procedures and the file they are defined in. After autoload has been executed to inform Tcl of the presence of them, a subsequent attempt to execute one of the procedures will cause the corresponding file to be loaded transparently prior to executing the function. If file is a name without directories, then the path is searched to locate the file. For example, executing:

autoload showproc.tcl showproc showprocs

tells Tcl to automatically load the file showproc.tcl the first time in the current session that either showproc or showprocs is executed.  

TCL PACKAGE LIBRARIES

Package libraries work like autoload, except that a package library file can contain multiple independent Tcl packages. A package is a collection of related Tcl procedures.

The package library file is just a regular Unix text file, editable with your favorite text editor, containing packages of Tcl source code. The package library file name must have the suffix .tlib. An index file with the suffix .tndx, corresponding to the package library, will be automatically created by Tcl whenever it is out of date.

The start of a package is delimited by:

#@package: package_name proc1 [..procN]

These lines must start in column one. Everything between the #@package: keyword and the next #@package: keyword or a #@packend keyword, or the end of the file, becomes part of the named package. The specified procedures, proc1..procN, are the entry points of the package. When a command named in a package specification is executed and detected as an unknown command, all code in the specified package will be sourced. This package should define all of the procedures named on the package line, define any support procedures required by the package and do any package-specific initialization. The #@packend keyword is useful to make sure only the minimum required section of code is sourced. Thus for example a large comment block at the beginning of the next file won't be loaded.

Care should be taken in defining package_name, as the first package found in the path by with a given name is loaded. This can be useful in developing new version of packages installed on the system.

For example, in a package source file, the presence of the following line:

#@package: directory_stack pushd popd dirs

says that the text lines following that line in the package file up to the next package line or the end of the file is a package named directory_stack and that an attempt to execute either pushd, popd or dirs when the routine is not already defined will cause the directory_stack portion of the package file to be loaded.  

PACKAGE INDEX FILES

A package library file has associated with it an index file called a .tndx file. The .tndx file contains the names of the packages in the .tlib file, their addresses and lengths within the .tlib file and the names of the functions that are to cause the various packages to be autoloaded when an attempt is made to execute them.

The first time Tcl tries to execute a procedure where the procedure doesn't exist and isn't an autoload, Tcl will search along TCLPATH looking for any files ending in .tlib. For each one it finds, it checks to see if there is a corresponding file in the same directory ending in .tndx. If the .tndx file doesn't exist, or if its date of last modification is older than that of the .tlib file, the .tndx is automatically (re)generated if possible. If Tcl can't regenerate the file (most likely due to file or directory permission problems), an error occurs. A .tndx file may also be explicitly built with the buildpackageindex procedure.

Demand loading is also supported from indexes build by the mkindex.tcl program, supplied with standard Tcl. However, init.tcl is not loaded. Note that the info library command is not used to locate libraries by this shell; the TCLPATH variable is set by the default file and is used to locate the libraries.  

PACKAGE LIBRARY MANAGEMENT COMMANDS

Several commands are available for building and managing package libraries. If you are not building package libraries and are using the standard Tcl initialization file, they are entirely transparent.

autoprocs Lists the names of all known autoload and package library procedures.

buildpackageindex libfile
Build an index for a package library. The the libfile name must end with the suffix .tlib.

convert_lib tclIndex packagelib [ignore]
Convert a Ousterhout style tclIndex index file and associate source files into a package library packagelib. If packagelib does not have a .tlib extension, one will be added. Any files specified in tclIndex that are in the list ignore will be skipped.

demand_load procname
Attempt to load the specified procedure, either as an autoload function or by loading the package containing the procedure. If the package indexes have not been loaded for all package libraries in TCLPATH, they will be loaded. Out-of-date library indexes will be rebuilt if they are writable. The procedure returns 1 if the procedure was sucessfully loaded, or 0 if it was not.

Duplicated package names are skipped, the first package of a given name found in the path is loaded.

loadlibindex libfile
Load the package library index of the library file libfile (which must have the suffix .tlib). Package library indexes along the TCLPATH are loaded automatically on the first demand_load; this command is provided to explicitly load libraries that are not in the path. If the index file (with a .tndx suffix) does not exists or is out of date, it will be rebuilt if the user has directory permissions to create it. Duplicated package names are skipped.

This command will also load an index built by mkindex.tcl program supplied with standard Tcl. This file must be named "tclIndex".

packages [-location]
Returns a list of the names of all defined packages. If -location is specified, the an keyed list is returned of package name and the values being a list of the .tlib path name, offset and length of the package within the library.

TCL PACKAGE LIBRARY PROCEDURES